guile-zenity
============

Version: 0.1

![logo](/guile-zenity.png)

Zenity is a command line tool that displays simple dialog boxes.

This library creates scheme procedures that build up a zenity command line, call it then parse the result and return it as scheme data.

* <https://help.gnome.org/users/zenity/stable/>
* <https://wiki.gnome.org/action/show/Projects/Zenity>
* <https://bugzilla.gnome.org/buglist.cgi?quicksearch=product%3Azenity>

installation
============

To use this you need to install the `zenity` program.

After than you need to move the `zenity.scm` file of this repo into your `GUILE_LOAD_PATH`.

To test that it's working try this:

```
$ guile
scheme@(guile-user)> (use-modules (zenity))
scheme@(guile-user)> (zenity-info "Hello world!")
Gtk-Message: GtkDialog mapped without a transient parent. This is discouraged.
$1 = #t
```

the warning can be ignored.

examples
========

There are two examples programs:

* `guile -l birthday.scm`: This programs asks your date of birth and sometimes wishes a happy birthday.
* `guile -l list-example.scm`: This program demonstrates using the list dialog (since it is a bit more complex to call than others).
* `guile -l todo.scm`: A more fun list example that lets you manage a todo list.
* `guile -l forms-example.scm`: Shows how to use the forms dialog.
* `guile -l egg-timer.scm`: Demonstrates the progress-bar feature - select a length of time then wait that long.
* `guile -l guix-helper.scm`: A sample program that helps build a guix package definition from forms filled in.

If you get an error like this:

```
ERROR: In procedure scm-error:
ERROR: no code for module (zenity)
```

try running it this way:

```
GUILE_LOAD_PATH=`pwd` guile -l examples/egg-timer.scm
```

that should help guile find the library.

functions
=========

## Calendar Dialog

`(zenity-calendar message)`

Shows a calendar for the user to pick a date from. The return value will be #f on Cancel, and an assoc list with fields `day`, `month`, `year` on success.


## Color Selection Dialog

`(zenity-color-selection #:key (color #f) (show-palette #f))`

This opens a color picker, it returns strings of the form "rgb(0,1,2)". You can preset the color by name e.g. `#:color "blue"`. By default it is a HSV color picker but you can change it to a palette by passing `#:show-palette #t`.


## File Selection Dialog

`(zenity-file-selection title #:key (multiple #f) (directory #f) (save #f) (filename #f))`

This opens up a dialog for choosing a file. There are keyword options to allow selecting multiple files, restricting it to directories only or making a new filename to save data to. A new keyword filename added to let you preset which directory the file might be chosen from.

Warning: A limitation of the way zenity outputs the file list (separated by the | character) is that this gives bad output on files with | in the name.


## Forms Dialog

`(zenity-forms title text layout)`

This produces a form built out of 'layout', layout is an assoc list of `(<type> . <name>)` pairs. The form field types are: `entry`, `password`, `calendar`. The field names are just strings.

The return value is a list: each piece of data entered by the user.

Warning: A limitation of the way zenity outputs data (separated by the , character) is that this will error if any data inputted contains the , character.


## List Dialog

`(zenity-list message columns rows)`
`(zenity-checklist message columns rows)`

Pass in list of columns and then a list of rows to let display and let an item be chosen from a list.

The return value of zenity-list is the selected row.
The return value of zenity-checklist is a list of the string versions of the first column of the selected items.


## Message Dialog

`(zenity-error message)`
`(zenity-info message)`
`(zenity-question message)`
`(zenity-warning message)`

Display a simple informational dialog box. The -question and -warning variants return a boolean for whether OK or Cancel was pressed.

## Scale Dialog

`(zenity-scale message #:key (value #f) (minimum #f) (maximum #f) (step #f) (hide-value #f))`

This dialog gives a slider to enable picking a number in a range.


## Password Dialog, Text Entry Dialog

`(zenity-password message)`
`(zenity-entry message)`

Asks the user for some input, the return value is #f on Cancel or the text that was inputted.


## 

`(zenity-pulsate message #:key (auto-close #f) (no-cancel #f) )`
`(zenity-progress message #:key (value #f) (auto-close #f) (no-cancel #f))`

These display a progress bar and return a new procedure while the dialog is still open.

* For pulsate the function returned is simply a thunk that you call when the computation is finished, this enables the Ok button.
* For progress the function returned takes one argument, a number from 0 to 100 indicating the progress of the operation. The Ok button appears when it reaches 100.


## Notes:

All these functions now accept the `#:width` and `#:height` keys to set the size of the dialog boxes.


contributors
============

* Raymond Nicholson <rain1@openmailbox.org
* Fabian Harfert <fhmgufs@opmbx.org>
